home *** CD-ROM | disk | FTP | other *** search
/ Apple WWDC 1996 / WWDC96_1996 (CD).toast / Technology Materials / MacOS 8 Resources / Developer Tools / Mac OS 8 Interfaces & Libraries / Interfaces / CIncludes / TimeObjects.h < prev    next >
C/C++ Source or Header  |  1996-05-01  |  17KB  |  468 lines
  1. /*
  2.      File:        TimeObjects.h
  3.  
  4.      Contains:    International Time Interfaces.
  5.  
  6.      Version:    Technology:    System 8
  7.                  Release:    Universal Interfaces 3.0d3 on Copland DR1
  8.  
  9.      Copyright:    © 1984-1996 by Apple Computer, Inc.  All rights reserved.
  10.  
  11.      Bugs?:        If you find a problem with this file, send the file and version
  12.                  information (from above) and the problem description to:
  13.  
  14.                      Internet:    apple.bugs@applelink.apple.com
  15.                      AppleLink:    APPLE.BUGS
  16.  
  17. */
  18. #ifndef __TIMEOBJECTS__
  19. #define __TIMEOBJECTS__
  20.  
  21. #ifndef __CONDITIONALMACROS__
  22. #include <ConditionalMacros.h>
  23. #endif
  24. #ifndef __KERNEL__
  25. #include <Kernel.h>
  26. #endif
  27. #ifndef __LOCALEOBJECTS__
  28. #include <LocaleObjects.h>
  29. #endif
  30. #ifndef __OSUTILS__
  31. #include <OSUtils.h>
  32. #endif
  33. #ifndef __TEXTOBJECTS__
  34. #include <TextObjects.h>
  35. #endif
  36. #ifndef __TIMING__
  37. #include <Timing.h>
  38. #endif
  39. #ifndef __TYPES__
  40. #include <Types.h>
  41. #endif
  42.  
  43. #ifdef __cplusplus
  44. extern "C" {
  45. #endif
  46.  
  47. #if PRAGMA_IMPORT_SUPPORTED
  48. #pragma import on
  49. #endif
  50.  
  51. #if PRAGMA_ALIGN_SUPPORTED
  52. #pragma options align=mac68k
  53. #endif
  54.  
  55. /*
  56.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  57.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  58.  ++                                                                                ++
  59.  ++                        Type definitions for Modern APIs                        ++
  60.  ++                                                                                ++
  61.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  62.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  63. */
  64. #if FOR_SYSTEM8_PREEMPTIVE
  65. /* Precision of TimeObject */
  66. typedef UInt8 TimeObjectPrecision;
  67.  
  68. enum {
  69.     kTONanosecondsPrecision        = 0x00,
  70.     kTOMicrosecondsPrecision    = 0x01,
  71.     kTOMillisecondsPrecision    = 0x02,
  72.     kTOSecondsPrecision            = 0x03,
  73.     kTOMinutesPrecision            = 0x04,
  74.     kTOHoursPrecision            = 0x05,
  75.     kTODaysPrecision            = 0x06
  76. };
  77.  
  78. /* Maximun Time Object Precision */
  79.  
  80. enum {
  81.     kTOMaxPrecision                = kTODaysPrecision
  82. };
  83.  
  84. typedef UInt32 TimeObjectNotificationRef;
  85. struct MachineLocationRecord {
  86.     Fixed                             longitude;
  87.     Fixed                             latitude;
  88.     TimeObjectInterval                 daylightSavingsDelta;
  89.     TimeObjectInterval                 utcDelta;
  90. };
  91. typedef struct MachineLocationRecord MachineLocationRecord;
  92.  
  93. typedef MachineLocationRecord *MachineLocationRecordPtr;
  94. typedef const MachineLocationRecord *ConstMachineLocationRecordPtr;
  95. struct UTCTimeRecord {
  96.     UInt16                             era;                        /* [0 = B.C.E., 1 = C.E. ]*/
  97.     UInt16                             year;                        /* [0, 65535]*/
  98.     UInt16                             month;                        /* [0,12]*/
  99.     UInt16                             day;                        /* [0,32]*/
  100.     UInt16                             hour;                        /* [0,23]*/
  101.     UInt16                             minute;                        /* [0,60]*/
  102.     UInt16                             seconds;                    /* [0,60]*/
  103.     UInt16                             milliseconds;                /* [0,1e3)*/
  104.     UInt32                             microseconds;                /* [0,1e6)*/
  105.     UInt32                             nanoseconds;                /* [0,1e9)*/
  106.     TimeObjectPrecision             precision;
  107. };
  108. typedef struct UTCTimeRecord UTCTimeRecord;
  109.  
  110. typedef UTCTimeRecord *UTCTimeRecordPtr;
  111. typedef const UTCTimeRecord *ConstUTCTimeRecordPtr;
  112. struct UTCTimeIntervalRecord {
  113.     SInt32                             day;
  114.     SInt32                             hour;
  115.     SInt32                             minute;
  116.     SInt32                             seconds;
  117.     SInt32                             milliseconds;
  118.     SInt32                             microseconds;
  119.     SInt32                             nanoseconds;
  120.     TimeObjectPrecision             precision;
  121. };
  122. typedef struct UTCTimeIntervalRecord UTCTimeIntervalRecord;
  123.  
  124. typedef UTCTimeIntervalRecord *UTCTimeIntervalRecordPtr;
  125. typedef const UTCTimeIntervalRecord *ConstUTCTimeIntervalRecordPtr;
  126. typedef UInt32 TimeObjectConversionType;
  127.  
  128. enum {
  129.     kUseRomanNumbers            = 0L,
  130.     kUseNativeNumbers            = 1L
  131. };
  132.  
  133. typedef LocaleObjectRef CalendarObjectRef;
  134. typedef TextObject TimeObjectFormatString;
  135. /* DateTimeFormat Types: */
  136. typedef UInt32 FormatStringRef;
  137.  
  138. enum {
  139.     kPreferredDateTimeFormat    = 0L,
  140.     kShortDateTimeFormat        = 1L,
  141.     kLongDateTimeFormat            = 2L,
  142.     kShortTimeFormat            = 3L,
  143.     kLongTimeFormat                = 4L
  144. };
  145.  
  146. #endif
  147. /*
  148.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  149.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  150.  ++                                                                                ++
  151.  ++                        Type definitions for Legacy APIs                        ++
  152.  ++                                                                                ++
  153.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  154.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  155. */
  156. #if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
  157. /*
  158.  
  159.     Here are the current routine names and the translations to the older forms.
  160.     Please use the newer forms in all new code and migrate the older names out of existing
  161.     code as maintainance permits.
  162.     
  163.     New Name                    Old Name(s)
  164.     
  165.     DateString                    IUDatePString IUDateString 
  166.     InitDateCache
  167.     LongDateString                IULDateString
  168.     LongTimeString                IULTimeString
  169.     StringToDate                String2Date
  170.     StringToTime                                
  171.     TimeString                    IUTimeString IUTimePString
  172. */
  173.  
  174. enum {
  175.     shortDate                    = 0,
  176.     longDate                    = 1,
  177.     abbrevDate                    = 2
  178. };
  179.  
  180. typedef SInt8 DateForm;
  181.  
  182. enum {
  183.                                                                 /* StringToDate status values */
  184.     fatalDateTime                = 0x8000,                        /* StringToDate and String2Time mask to a fatal error */
  185.     longDateFound                = 1,                            /* StringToDate mask to long date found */
  186.     leftOverChars                = 2,                            /* StringToDate & Time mask to warn of left over characters */
  187.     sepNotIntlSep                = 4,                            /* StringToDate & Time mask to warn of non-standard separators */
  188.     fieldOrderNotIntl            = 8,                            /* StringToDate & Time mask to warn of non-standard field order */
  189.     extraneousStrings            = 16,                            /* StringToDate & Time mask to warn of unparsable strings in text */
  190.     tooManySeps                    = 32,                            /* StringToDate & Time mask to warn of too many separators */
  191.     sepNotConsistent            = 64,                            /* StringToDate & Time mask to warn of inconsistent separators */
  192.     tokenErr                    = 0x8100,                        /* StringToDate & Time mask for 'tokenizer err encountered' */
  193.     cantReadUtilities            = 0x8200,
  194.     dateTimeNotFound            = 0x8400,
  195.     dateTimeInvalid                = 0x8800
  196. };
  197.  
  198. typedef short StringToDateStatus;
  199. typedef short String2DateStatus;
  200. struct DateCacheRecord {
  201.     short                             hidden[256];                /* only for temporary use */
  202. };
  203. typedef struct DateCacheRecord DateCacheRecord;
  204.  
  205. typedef DateCacheRecord *DateCachePtr;
  206. #endif
  207. /*
  208.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  209.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  210.  ++                                                                                ++
  211.  ++                                Modern API Definitions                            ++
  212.  ++                                                                                ++
  213.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  214.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  215. */
  216. #if FOR_SYSTEM8_PREEMPTIVE
  217. /*
  218.  *********************************************************
  219.  *
  220.  * TimeObject Constructors
  221.  *
  222.  *********************************************************
  223. */
  224. extern OSStatus CreateTimeObject(TimeObjectPtr timeObject, ConstUTCTimeRecordPtr utcTime);
  225.  
  226. extern OSStatus CreateTimeObjectInterval(TimeObjectIntervalPtr timeObjectInterval, ConstUTCTimeIntervalRecordPtr utcTimeInterval);
  227.  
  228. /*
  229.  *********************************************************
  230.  *
  231.  * Getter and Setter Functions for TimeObjects
  232.  *
  233.  *********************************************************
  234. */
  235. extern OSStatus GetCurrentTime(TimeObjectPtr timeObj);
  236.  
  237. extern OSStatus SetCurrentTime(ConstTimeObjectPtr timeObj);
  238.  
  239. /*
  240.  *********************************************************
  241.  *
  242.  * Getter and Setter Functions for Machine Location
  243.  *
  244.  *********************************************************
  245. */
  246. extern OSStatus GetMachineLocation(MachineLocationRecordPtr machineLocation);
  247.  
  248. extern OSStatus SetMachineLocation(ConstMachineLocationRecordPtr machineLocation);
  249.  
  250. /*
  251.  *********************************************************
  252.  *
  253.  * Getter and Setter Functions for TimeObjects Precision
  254.  *
  255.  *********************************************************
  256. */
  257. extern OSStatus GetTimeObjectPrecision(ConstTimeObjectPtr timeObj, TimeObjectPrecision *precision);
  258.  
  259. extern OSStatus SetTimeObjectPrecision(TimeObjectPtr timeObj, TimeObjectPrecision precision);
  260.  
  261. extern OSStatus GetTimeObjectIntervalPrecision(ConstTimeObjectIntervalPtr timeObj, TimeObjectPrecision *precision);
  262.  
  263. extern OSStatus SetTimeObjectIntervalPrecision(TimeObjectIntervalPtr timeObj, TimeObjectPrecision precision);
  264.  
  265. /*
  266.  *********************************************************
  267.  *
  268.  * Timers
  269.  *
  270.  *********************************************************
  271. */
  272. extern OSStatus CreateTimeObjectNotifier(ConstTimeObjectPtr timeObject, KernelNotification *notifier, TimeObjectNotificationRef *notificationRef);
  273.  
  274. extern OSStatus CancelTimeObjectNotifier(TimeObjectNotificationRef notificationRef);
  275.  
  276. /*
  277.  *********************************************************
  278.  *
  279.  * Manipulation and Comparison functions for TimeObjects
  280.  *
  281.  *********************************************************
  282. */
  283. extern OSStatus AddToFixedTimeObject(ConstTimeObjectPtr fixedTimeObj, ConstTimeObjectIntervalPtr offsetTimeObj, TimeObjectPtr result);
  284.  
  285. extern OSStatus AddTimeObjectIntervals(ConstTimeObjectIntervalPtr timeObj1, ConstTimeObjectIntervalPtr timeObj2, TimeObjectIntervalPtr result);
  286.  
  287. extern OSStatus SubtractFromFixedTimeObject(ConstTimeObjectPtr fixedTimeObj, ConstTimeObjectIntervalPtr offsetTimeObj, TimeObjectPtr result);
  288.  
  289. extern OSStatus SubtractTimeObjectIntervals(ConstTimeObjectIntervalPtr timeObj1, ConstTimeObjectIntervalPtr timeObj2, TimeObjectIntervalPtr result);
  290.  
  291. extern OSStatus SubtractFixedTimeObjects(ConstTimeObjectPtr timeObj1, ConstTimeObjectPtr timeObj2, TimeObjectIntervalPtr result);
  292.  
  293. extern OSStatus CompareFixedTimeObjects(ConstTimeObjectPtr timeObj1, ConstTimeObjectPtr timeObj2, ConstTimeObjectIntervalPtr precision, SInt32 *result);
  294.  
  295. extern OSStatus CompareTimeObjectIntervals(ConstTimeObjectIntervalPtr timeObj1, ConstTimeObjectIntervalPtr timeObj2, ConstTimeObjectIntervalPtr precision, SInt32 *result);
  296.  
  297. /*
  298.  *********************************************************
  299.  *
  300.  * TimeObjects to Seconds from 1/1/04 conversion functions
  301.  *
  302.  *********************************************************
  303. */
  304. extern OSStatus ConvertSecondsToTimeObject(UInt32 seconds, TimeObjectPtr convertedTimeObj);
  305.  
  306. extern OSStatus ConvertTimeObjectToSeconds(ConstTimeObjectPtr timeObj, UInt32 *seconds);
  307.  
  308. extern OSStatus ConvertLongDateTimeToTimeObject(LongDateTime *longDateTime, TimeObjectPtr convertedTimeObj);
  309.  
  310. extern OSStatus ConvertTimeObjectToLongDateTime(ConstTimeObjectPtr timeObj, LongDateTime *longDateTime);
  311.  
  312. /*
  313.  *********************************************************
  314.  *
  315.  * TimeObjectIntervals to Nanosecond conversion functions
  316.  *
  317.  *********************************************************
  318. */
  319. extern OSStatus ConvertTimeObjectIntervalToNanoseconds(ConstTimeObjectIntervalPtr source, Nanoseconds *result);
  320.  
  321. extern OSStatus ConvertNanosecondsToTimeObjectInterval(Nanoseconds *source, TimeObjectIntervalPtr result);
  322.  
  323. /*
  324.  *********************************************************
  325.  *
  326.  * Internet Time/Mail Conversion Routines
  327.  *
  328.  *********************************************************
  329. */
  330. extern OSStatus ConvertTimeObjectToInternetMailTime(ConstTimeObjectPtr source, TextObject result);
  331.  
  332. extern OSStatus ConvertInternetMailTimeToTimeObject(TextObject source, TimeObjectPtr result);
  333.  
  334. extern OSStatus ConvertTimeObjectToInternetTime(ConstTimeObjectPtr source, UInt32 *result);
  335.  
  336. extern OSStatus ConvertInternetTimeToTimeObject(UInt32 internetTime, TimeObjectPtr result);
  337.  
  338. /*
  339.  *********************************************************
  340.  *
  341.  * Calendar Routines
  342.  *
  343.  *********************************************************
  344. */
  345. extern OSStatus GetDefaultCalendar(LocaleRef theLocale, CalendarObjectRef *theCalendar);
  346.  
  347. extern OSStatus GetDefaultSystemCalendar(CalendarObjectRef *theCalendar);
  348.  
  349. /*
  350.  *********************************************************
  351.  *
  352.  * Text Conversion Routines
  353.  *
  354.  *********************************************************
  355. */
  356. extern OSStatus ConvertTimeObjectToDateString(ConstTimeObjectPtr timeObj, CalendarObjectRef theCalendar, TextObject textObj, TimeObjectFormatString format, FormatStringRef formatSelector, TimeObjectConversionType conversionSelector);
  357.  
  358. extern OSStatus ConvertTimeObjectToTimeString(ConstTimeObjectIntervalPtr timeObjectInterval, CalendarObjectRef theCalendar, TextObject textObj, TimeObjectFormatString format, FormatStringRef formatSelector, TimeObjectConversionType conversionSelector);
  359.  
  360. extern OSStatus ConvertDateStringToTimeObject(TimeObjectPtr timeObj, CalendarObjectRef theCalendar, TextObject textObj, TimeObjectConversionType conversionSelector);
  361.  
  362. extern OSStatus ConvertTimeStringToTimeObject(TimeObjectIntervalPtr timeObjectInterval, CalendarObjectRef theCalendar, TextObject textObj, TimeObjectConversionType conversionSelector);
  363.  
  364. #endif
  365. /*
  366.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  367.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  368.  ++                                                                                ++
  369.  ++                                Legacy API Definitions                            ++
  370.  ++                                                                                ++
  371.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  372.  +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
  373. */
  374. #if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
  375. /*
  376.  **************************************************************************************
  377.  *
  378.  * The following functions are new names that work on 68k and PowerPC
  379.  *
  380.  **************************************************************************************
  381. */
  382. extern pascal OSErr InitDateCache(DateCachePtr theCache)
  383.  FOURWORDINLINE(0x2F3C, 0x8204, 0xFFF8, 0xA8B5);
  384.  
  385. extern pascal StringToDateStatus StringToDate(Ptr textPtr, long textLen, DateCachePtr theCache, long *lengthUsed, LongDateRec *dateTime)
  386.  FOURWORDINLINE(0x2F3C, 0x8214, 0xFFF6, 0xA8B5);
  387.  
  388. extern pascal StringToDateStatus StringToTime(Ptr textPtr, long textLen, DateCachePtr theCache, long *lengthUsed, LongDateRec *dateTime)
  389.  FOURWORDINLINE(0x2F3C, 0x8214, 0xFFF4, 0xA8B5);
  390.  
  391. extern pascal void IUDateString(long dateTime, DateForm longFlag, Str255 result)
  392.  TWOWORDINLINE(0x4267, 0xA9ED);
  393.  
  394. extern pascal void IUTimeString(long dateTime, Boolean wantSeconds, Str255 result)
  395.  THREEWORDINLINE(0x3F3C, 0x0002, 0xA9ED);
  396.  
  397. extern pascal void IUDatePString(long dateTime, DateForm longFlag, Str255 result, Handle intlHandle)
  398.  THREEWORDINLINE(0x3F3C, 0x000E, 0xA9ED);
  399.  
  400. extern pascal void IUTimePString(long dateTime, Boolean wantSeconds, Str255 result, Handle intlHandle)
  401.  THREEWORDINLINE(0x3F3C, 0x0010, 0xA9ED);
  402.  
  403. extern pascal void IULDateString(LongDateTime *dateTime, DateForm longFlag, Str255 result, Handle intlHandle)
  404.  THREEWORDINLINE(0x3F3C, 0x0014, 0xA9ED);
  405.  
  406. extern pascal void IULTimeString(LongDateTime *dateTime, Boolean wantSeconds, Str255 result, Handle intlHandle)
  407.  THREEWORDINLINE(0x3F3C, 0x0016, 0xA9ED);
  408.  
  409. /*
  410.  **************************************************************************************
  411.  *
  412.  * The following are macros which map new names to the names exported by InterfaceLib
  413.  *
  414.  **************************************************************************************
  415. */
  416. #define DateString(dateTime, longFlag, result, intlHandle) \
  417.          IUDatePString( dateTime, longFlag, result, intlHandle)
  418. #define TimeString(dateTime, wantSeconds, result, intlHandle) \
  419.          IUTimePString(dateTime, wantSeconds, result, intlHandle)
  420. #define LongDateString(dateTime, longFlag, result, intlHandle) \
  421.          IULDateString(dateTime, longFlag, result, intlHandle)
  422. #define LongTimeString(dateTime, wantSeconds, result, intlHandle) \
  423.          IULTimeString(dateTime, wantSeconds, result, intlHandle)
  424. /*
  425.  **************************************************************************************
  426.  *
  427.  * The following are macros which map old names to the names exported by InterfaceLib
  428.  *
  429.  **************************************************************************************
  430. */
  431. #if CGLUESUPPORTED
  432. #if OLDROUTINENAMES
  433. extern void iudatestring(long dateTime, DateForm longFlag, char *result);
  434.  
  435. extern void iudatepstring(long dateTime, DateForm longFlag, char *result, Handle intlHandle);
  436.  
  437. extern void iutimestring(long dateTime, Boolean wantSeconds, char *result);
  438.  
  439. extern void iutimepstring(long dateTime, Boolean wantSeconds, char *result, Handle intlHandle);
  440.  
  441. extern void iuldatestring(LongDateTime *dateTime, DateForm longFlag, char *result, Handle intlHandle);
  442.  
  443. extern void iultimestring(LongDateTime *dateTime, Boolean wantSeconds, char *result, Handle intlHandle);
  444.  
  445. #define String2Date(textPtr, textLen, theCache, lengthUsed, dateTime)  \
  446.          StringToDate(textPtr, textLen, theCache, lengthUsed, dateTime)
  447. #define String2Time(textPtr, textLen, theCache, lengthUsed, dateTime)  \
  448.          StringToTime(textPtr, textLen, theCache, lengthUsed, dateTime)
  449. #else
  450. #endif
  451. #endif
  452. #endif
  453.  
  454. #if PRAGMA_ALIGN_SUPPORTED
  455. #pragma options align=reset
  456. #endif
  457.  
  458. #if PRAGMA_IMPORT_SUPPORTED
  459. #pragma import off
  460. #endif
  461.  
  462. #ifdef __cplusplus
  463. }
  464. #endif
  465.  
  466. #endif /* __TIMEOBJECTS__ */
  467.  
  468.